Upload Media For Message
The Upload API allows you to upload media files.
Before You Start
This guide assumes you have read the Before You Start section.
You will need:
- A user access token
For Media Uploads-
The Media to be provided while sending the carousel Messages or message using media ID needs to be pre-uploaded on the Meta Servers-else the carousel Messages/media message with media id will not get delivered-The Media Upload for Message is a 2 Step process as mentioned below-
Step-1:
Enterprises must send the request using the below endpoint to get the Media Acknowledgement ID
Steps for uploading media:
Send a POST request.
UAT Endpoint- https://apiuat.aclwhatsapp.com/access-api/api/v1/wa/{waba-id}/media/upload-
Production Endpoint- https://api.aclwhatsapp.com/access-api/api/v1/wa/{waba-id}/media/upload-
Sample Curl-
url --location 'https://apiuat.aclwhatsapp.com/access-api/api/v1/wa/177384039855054/media/upload' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Token>' \
--data '{
"mediaUrl": "https://download.samplelib.com/mp3/sample-3s.mp3",
"mediaFormat": "audio/mpeg",
"always_upload": false
}'
Request Type- POST
Header Values-
| Name | Value |
|---|---|
| Content-Type | Fixed value application/json |
| Authorization | Bearer token - (generated using Token API as mentioned above) |
Data Object Values-
| Name | Description | Value |
|---|---|---|
| mediaFormat | Mime Types of Media as supported by Meta | application/pdf |
| mediaUrl | Publicly accessible Media URL | |
| always_upload | Boolean value determining if media needs to reuploaded even if mediaId is already present |
The above request will return a Media- Acknowledgement ID- As a response as mentioned below:
{
"acknowledgementId": "1752915620015378432",
"acceptedTime": 1706762626066
}
Error & Exceptions-
- Duplicate Request (without always upload) - If the User has send the Multiple request to upload the same media file with always_upload false.
{
"mediaId": "6fba7ef1-f845-4063-b96a-f814058213f2",
"acknowledgementId": "1752915620015378432",
"error": "duplicate.media.upload.request"
}
- Duplicate Request (with always upload) - If the User has send the Multiple request to upload the same media file with always_upload true but the existing media was uploaded within last 7 days .
{
"mediaId": "6fba7ef1-f845-4063-b96a-f814058213f2",
"acknowledgementId": "1752915620015378432",
"error": "duplicate.media.upload.request"
}
- Rate limit Error- Enterprise can send only 1 Media upload request per sender - In case any other media upload request is already in progress for that particular sender the system will return an error as 400 with below message.
{
"error": "request.limit.exceeded"
}
Step-2- After receiving the Media Acknowledgement ID-the user will use the below request to fetch the exact Media ID to be used for sending the carousel Templated Messages.
UAT Endpoint- https://apiuat.aclwhatsapp.com/access-api/api/v1/wa/{waba-id}/media
Production Endpoint- https://api.aclwhatsapp.com/access-api/api/v1/wa/{waba-id}/media
Request Type- POST Sample Curl-
curl --location 'https://apiuat.aclwhatsapp.com/access-api/api/v1/wa/{wabaid}/media'--header 'Authorization: Bearer <token>'--header 'Content-Type:
application/json'--data '{"acknowledgementId": "1752915620015378432"}'
Header Values-
| Name | Value |
|---|---|
| Content-Type | Fixed value application/json |
| Authorization | Bearer token - (generated using Token API as mentioned above) |
Data Object Values-
| Name | Description | Value |
|---|---|---|
| acknowledgementId | ID generated while uploading the Media in step-1 | 1752915620015378432 |
The above request will return a Media- Acknowledgement ID- As a response as mentioned below-
{
"mediaId": "6fba7ef1-f845-4063-b96a-f814058213f2",
"acknowledgementId": "1752915620015378432",
"mediaUrl": "https://download.samplelib.com/mp3/sample-3s.mp3",
"expiryTime": 1707972226000,
"status": "success"
}
Response Details-
• Media Id- To be used for sending the Carousel message. • acknowledgementId - Provided in the request • mediaUrl – The web URL provided for uploading the media • expiry Time- The time by which media will be available in Meta Servers- Post that the User have to re-upload the media in order to send them in the message.
Error & Exceptions-
- Upload In Progress- If the Media Upload is still in progress at Meta servers following response will be provided by the request.
{
"acknowledgementId": "1755474606652657662",
"mediaUrl": "https://picsum.photos/id/237/200/301",
"expiryTime": 1708582336000,
"status": "media.generation.in.progress",
"errors": [
{
"desc": "Media upload is in progress"
}
]
}
- Media Not Found- In case the Media Expires following response will be provided to the client-
{
"acknowledgementId": "1755473752088383468",
"status": "media.not.found"
}
- Media Generation Failed- In case the Media upload is failed at Meta Servers following response will be provided to client
{
"acknowledgementId": "1755477593324261376",
"mediaUrl": "https://picsum.phots/id/237/200/30",
"expiryTime": 1708583048000,
"status": "media.generation.failed",
"errors": [
{
"code": "502",
"desc": "Something went wrong while generating mediaId, please try again"
}
]
}